home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.097 < prev    next >
Encoding:
Text File  |  1991-01-11  |  7.6 KB  |  156 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6. Apple IIgs
  7. #97:    Picture Comments and Printing
  8.  
  9. Written by:    Matt Deatherage, Suki Lee & Ben Koning           November 1990
  10.  
  11. This Technical Note discusses QuickDraw Auxiliary picture comments and how they
  12. can be used to help control the printing process.
  13. _____________________________________________________________________________
  14.  
  15.  
  16. What's a Picture Comment?
  17.  
  18. Picture comments are a way in which extra information beyond normal QuickDraw II
  19. calls can be embedded in a QuickDraw II picture.  Comments can contain virtually
  20. anything; they consist of a length, a handle containing the comment and a "kind"
  21. that identifies the general type of information in the comment.  Picture comment
  22. kinds less than or equal to 256 ($100) are reserved for Apple Computer, Inc.
  23.  
  24. For comments to have any significance, there must be a way that a routine can
  25. take special action on them.  One of the standard bottleneck procedures is
  26. called every time a picture comment is encountered, and it is passed the picture
  27. comment's kind, size, and handle on QuickDraw II's direct page.  You can insert
  28. the address of a custom picture comment handler into the grafProcs field of a
  29. grafPort as described in Apple IIgs Technical Note #34, Low-Level QuickDraw II
  30. Routines.  If no custom comment handler is present in the grafPort, the system
  31. calls its own StdComment routine, which ignores all comments.
  32.  
  33. The current picture comment handling routine (either a custom one or the
  34. system's default one) is called whenever a picture comment is generated (with
  35. the QuickDraw Auxiliary call PicComment) or played back from a picture (from
  36. within DrawPicture).  Since the picture comment handling procedure is called
  37. when the comment is created, a picture does not have to be open for this
  38. facility to work.
  39.  
  40. Picture comments are ideal ways for applications to pass information to printer
  41. drivers as they are generated through toolbox calls and are easily accessible to
  42. any desktop program.  If the printer driver is printing in immediate mode, it
  43. can intercept and act on the picture comment when it is generated.  If the
  44. printer driver is printing in deferred mode and recording page images with
  45. QuickDraw II pictures, it can intercept and act on the picture comment when the
  46. picture is played back.
  47.  
  48. Apple's ImageWriter, ImageWriter LQ and LaserWriter drivers (from System
  49. Software 5.0.3) all support various kinds of picture comments for controlling
  50. printed output.  Applications are encouraged to use these picture comments for
  51. finer control over printing.  Authors of printer drivers are encouraged to act
  52. on these picture comments where appropriate, so applications which use them
  53. achieve similar results across printing platforms.
  54.  
  55.  
  56. The LaserWriter Driver's Picture Comments
  57.  
  58. Version 2.2 and later of the LaserWriter driver support the following five
  59. PostScriptr picture comments:
  60.  
  61.           Name              Kind    Size    Handle
  62.           ------------------------------------------------------
  63.           PostScriptBegin   190     0       NIL
  64.           PostScriptEnd     191     0       NIL
  65.           PostScriptHandle  192     -       PostScript data
  66.           PostScriptFile    193     -       PostScript path name
  67.           TextIsPostScript  194     0       NIL
  68.           ------------------------------------------------------
  69.  
  70.                       Table 1-PostScript Picture Comments
  71.  
  72. The print loop must be completed normally with or without any PostScript picture
  73. comments that are included.  PostScript transmission must begin with the
  74. PostScriptBegin picture comment and end with the PostScriptEnd picture comment.
  75. Never nest PostScriptBegin and PostScriptEnd picture comments.
  76.  
  77. The PostScriptHandle picture comment takes a handle containing PostScript
  78. commands (in the form of ASCII data) and sends it to the LaserWriter.  The size
  79. field must contain the size of the handle.
  80.  
  81. The PostScriptFile picture comment takes a handle containing the pathname of a
  82. disk file containing PostScript commands.  The size field must contain the size
  83. of the pathname.
  84.  
  85. The TextIsPostScript picture comment takes text drawn through the QuickDraw II
  86. StdText bottleneck and sends it to the LaserWriter as PostScript.  This picture
  87. comment has the effect, from the application's point of view, of interpreting
  88. all strings passed to DrawString and similar calls as PostScript.  This picture
  89. comment is specific to LaserWriters (idev = $0003).  Other drivers do not
  90. implement this picture comment; therefore, text drawn through QuickDraw II is
  91. simply printed-it is neither interpreted as PostScript nor ignored.
  92.  
  93. The driver does not check for PostScript errors, so the data sent to the
  94. LaserWriter must be correct.  Always terminate PostScript text with a carriage
  95. return character.  The transformation the driver uses flips text and prints it
  96. upside down on the page.  Applications should set their own transformation
  97. matrices to serve their needs.  Never use the LaserWriter's userdict-define a
  98. local dictionary for your application's use.  Never use exitserver,
  99. initgraphics, grestoreall, erasepage, or showpage PostScript commands, as these
  100. commands can alter the driver's environment.
  101.  
  102. See Chapter 3 of the LaserWriter Reference Manual for some examples of how to
  103. use picture comments.
  104.  
  105.  
  106. The ImageWriter Driver's Picture Comments
  107.  
  108. ImageWriter driver version 4.0 and later uses three picture comments to control
  109. alternate color selection:
  110.  
  111.                   Name            Kind    Size    Handle
  112.                   -----------------------------------------
  113.                     Reserved        250     -       Reserved
  114.                    FillColorTable  251     42      See below
  115.                    ChangeSCBs      252     14      See below
  116.                   -----------------------------------------
  117.  
  118. The structure passed in the handle to FillColorTable looks like the following:
  119.  
  120.           version     word       must be zero
  121.           signature   word       must be $A55A
  122.           tableno     word       the color table to be modified (0-15)
  123.           table       32 bytes   The new color values for the color table
  124.           reserved    long       must be zero
  125.  
  126. The structure passed in the handle to ChangeSCBs looks like the following:
  127.  
  128.           version     word       must be zero
  129.           signature   word       must be $A55A
  130.           Y1          word       line number of first SCB to change (from zero
  131.                                  to rPage.Y2)
  132.           Y2          word       line number of last SCB to change (from zero to
  133.                                  rPage.Y2)
  134.           SCBvalue    word       the new scan line control byte
  135.           reserved    long       must be zero
  136.  
  137. PrOpenPage reinitializes the printing grafPort, so these picture comments should
  138. be used immediately after PrOpenPage to set custom colors.  Having lines with
  139. both 320- and 640-mode is not recommended and will probably not be supported in
  140. the future.
  141.  
  142. The ImageWriter driver uses picture comment 250 to internally mark the end of a
  143. page.  Applications must not use this picture comment; use PrClosePage to end a
  144. page's definition.
  145.  
  146.  
  147. Further Reference
  148. _____________________________________________________________________________
  149.   o     Apple IIgs Toolbox Reference, Volumes 1-3
  150.   o     Apple IIgs Technical Note #34, Low-Level QuickDraw II Routines
  151.   o     Apple IIgs Technical Note #35, Printer Driver Specifications
  152.   o     Apple IIgs Technical Note #93, Compatible Printing
  153.   o     d e v e l o p, October 1990, Issue 4, "Driving to Print"
  154.  
  155. PostScript is a registered trademark of Adobe Systems, Incorporated.
  156.